Intl: Add a new IntlNumberRangeFormatter class #19232

BogdanUngureanu · 2025-07-24T23:00:45Z

Adds support for ICU's NumberRangeFormatter that returns a locale-aware string interval given 2 numbers. Instead of using the C API, I've opted for the C++ one because it offers a few more possibilities in the future (it could combined with a new NumberFormatter ICU class) while the C version only allows support for skeleton strings.

Since the new NumberFormatter class hasn't been added to PHP Intl yet, the implementation uses skeletons for now.

The implementation uses a factory method that returns a new IntlNumberRangeFormatter object, while the constructor is private. I went with this approach because it would allow the class to have a second factory method in the future for different number formatting (e.g. NumberFormatter). Something like

createFromSkeleton(...)
createFromNumberFormatter()

Drawbacks of the current PHP API:
The C++ version allows to configure the NumberFormatter/skeleton for $start and $end individually (using a fluent interface). The PHP API I propose sets it for both numbers
C++ example code:

NumberRangeFormatter::with()
    .identityFallback(UNUM_IDENTITY_FALLBACK_APPROXIMATELY_OR_SINGLE_VALUE)
    .numberFormatterFirst(NumberFormatter::with().adoptUnit(MeasureUnit::createMeter()))
    .numberFormatterSecond(NumberFormatter::with().adoptUnit(MeasureUnit::createKilometer()))
    .locale("en-GB")
    .formatFormattableRange(750, 1.2, status)
    .toString(status);
// => "750 m - 1.2 km"

and a C example

// Setup:
UErrorCode ec = U_ZERO_ERROR;
UNumberRangeFormatter* uformatter = unumrf_openForSkeletonCollapseIdentityFallbackAndLocaleWithError(
    u"currency/USD precision-integer",
    -1,
    UNUM_RANGE_COLLAPSE_AUTO,
    UNUM_IDENTITY_FALLBACK_APPROXIMATELY,
    "en-US",
    NULL,
    &ec);
UFormattedNumberRange* uresult = unumrf_openResult(&ec);
if (U_FAILURE(ec)) { return; }

// Format a double range:
unumrf_formatDoubleRange(uformatter, 3.0, 5.0, uresult, &ec);
if (U_FAILURE(ec)) { return; }

// Get the result string:
int32_t len;
const UChar* str = ufmtval_getString(unumrf_resultAsValue(uresult, &ec), &len, &ec);
if (U_FAILURE(ec)) { return; }
// str should equal "$3 – $5"

While the code works, the work is still in progress - I still have to implement a proper error handling. In the meantime, I would like to hear your opinions about the PHP interface I'm proposing.

ext/intl/rangeformatter/rangeformatter.stub.php

kocsismate · 2025-07-25T17:22:00Z

ext/intl/rangeformatter/rangeformatter.stub.php

+
+    private function __construct() {}
+
+    public static function createFromSkeleton(string $skeleton, string $locale, int $collapse, int $identityFallback): IntlNumberRangeFormatter {}


I hope I won't upset you too much, but I think these changes will need an RFC, because any API changes involve a lot of bikeshedding lately.

For example, we have started to use enums more often (see my https://wiki.php.net/rfc/url_parsing_api RFC), so I think this practice could be continued in your case too.

Hm, I see that you have recently added the ListFormatter class in #18519 that also has some enum-like constants. It probably also makes sense to stay consistent with the current convention of intl (class constants), so I don't insist on my above suggestion.

If we decide that we should employ nicer features in intl, we should do a thorough review of not only the constants ,but other mechanisms (like error handling) as well. And then we can make one compelling holistic RFC (if we would desire to do so ;) ).

Hm, I see that you have recently added the ListFormatter class in #18519 that also has some enum-like constants. It probably also makes sense to stay consistent with the current convention of intl (class constants), so I don't insist on my above suggestion.

Yeah, that was my reasoning. Since that one didn't need an RFC, I thought this one also won't need it.

If we decide that we should employ nicer features in intl, we should do a thorough review of not only the constants ,but other mechanisms (like error handling) as well. And then we can make one compelling holistic RFC (if we would desire to do so ;) ).

Sounds fair. I think for now the API I'm proposing is ok. I do agree introducing the new NumberFormatter will require an RFC.

ext/intl/rangeformatter/rangeformatter_class.cpp

ext/intl/rangeformatter/rangeformatter.stub.php

ext/intl/rangeformatter/rangeformatter_class.cpp

BogdanUngureanu · 2025-08-03T22:15:05Z

The test failure for [Push / WINDOWS_X64_ZTS (pull_request)](https://github.com/php/php-src/actions/runs/16698635741/job/47266273580?pr=19232)Failing after 31m seems to be a false positive? It doesn't fail for the other ones.

@devnexen @kocsismate when you have some spare time, can you look at the PR again? Thanks.

ext/intl/rangeformatter/rangeformatter_class.cpp

ext/intl/tests/rangeformatter/basic.phpt

Girgias · 2025-08-07T23:42:26Z

ext/intl/rangeformatter/rangeformatter_class.cpp

+        intl_error_set(NULL, error, "Failed to format number range");
+        zend_throw_exception(IntlException_ce_ptr, "Failed to format number range", 0);


intl_error_set may already throw an exception, or emit a warning, or do nothing depending on the error mode selected.

If you decide to always throw, then just throw an exception directly rather than going through its internal error mechanism.
Or you need to do what I did for constructors:

const bool old_use_exception = INTL_G(use_exceptions); const zend_long old_error_level = INTL_G(error_level); INTL_G(use_exceptions) = true; INTL_G(error_level) = 0; intl_error_set(NULL, error, "Failed to format number range"); INTL_G(use_exceptions) = old_use_exception; INTL_G(error_level) = old_error_level;

However, if it seems you always just throw exceptions for any failure condition. So always throwing exceptions would allow you to forego carrying the intl_error struct around in rangeformatter_data which would make the overall RangeFormatter class take a smaller memory footprint.

If you decide to always throw, then just throw an exception directly rather than going through its internal error mechanism.

I've used intl_error_set so the behavior is consistent with the other classes. Without it, functions like intl_get_error_code() and intl_get_error_message() likely won’t work properly. It’s also used for IntlNumberRangeFormatter::getErrorCode() and IntlNumberRangeFormatter::getErrorMessage().

Another option would be to drop the exception and rely on intl_error_set, but that means format will have to return a falsy value on failure, which personally I would prefer not to because the return value signature will need to be changed to string|false.

I'm fine either way, just wanted to mention the reasoning. :)

nielsdos · 2025-08-09T20:20:14Z

ext/intl/rangeformatter/rangeformatter_class.cpp

+
+U_CFUNC PHP_METHOD(IntlNumberRangeFormatter, createFromSkeleton)
+{
+#if U_ICU_VERSION_MAJOR_NUM < 63


? So how will this even compile then on older versions? Shouldn't this entire class be compiled conditionally instead of adding exception code at the top?

Yes, that's correct, it would compile to other versions. I think it's more developer friendly to know why the class is not available with their configuration - doing it like this, the developer knows that the class is not available because of the ICU constraint. Otherwise, they'll get a fatal for a non-existent class which would feel confusing imo.

It was previously discussed here too. :)

BogdanUngureanu requested review from kocsismate and devnexen as code owners July 24, 2025 23:00

github-actions bot added Category: Build System Extension: intl labels Jul 24, 2025